home *** CD-ROM | disk | FTP | other *** search
- DLOPEN(3C) Last changed: 2-23-99
-
-
- NNAAMMEE
- ddllooppeenn, ssggiiddllooppeenn__vveerrssiioonn - Opens a Dynamic Shared Object (DSO)
-
- SSYYNNOOPPSSIISS
- cccc [_o_p_t_i_o_n_s ...] _f_i_l_e ...... --llcc [_l_i_b_r_a_r_y ......]
-
- ##iinncclluuddee <<ddllffccnn..hh>> (Required for both ddllooppeenn and for
- ssggiiddllooppeenn__vveerrssiioonn)
-
- ##iinncclluuddee <<eellff..hh>> (Required for ssggiiddllooppeenn__vveerrssiioonn only)
-
- vvooiidd **ddllooppeenn((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _m_o_d_e_1 [ || _m_o_d_e_2 ]));;
-
- vvooiidd **ssggiiddllooppeenn__vveerrssiioonn((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _m_o_d_e_1 [ || _m_o_d_e_2 ],,
- ccoonnsstt cchhaarr **_v_e_r_s_i_o_n,, iinntt _f_l_a_g_s));;
-
- IIMMPPLLEEMMEENNTTAATTIIOONN
- IRIX systems
-
- DDEESSCCRRIIPPTTIIOONN
- ddllooppeenn and ssggiiddllooppeenn__vveerrssiioonn belong to a family of routines that
- provides direct access to the dynamic linking facilities. These
- routines are available in a library that is loaded if the --llcc option
- is used with the CCCC(1), cccc(1), ff9900(1), ff7777(1), or lldd(1) command lines.
-
- ddllooppeenn makes a shared object available to a running process. It
- returns a handle to the process, which the process can use on
- subsequent calls to ddllssyymm(3C) and ddllcclloossee(3C). This handle should not
- be interpreted in any way by the process.
-
- ssggiiddllooppeenn__vveerrssiioonn dynamically loads DSOs in a way similar to ddllooppeenn.
- However, unlike ddllooppeenn, the interface version of the DSO is specified
- (on the _v_e_r_s_i_o_n and _f_l_a_g_s arguments) so that the dynamic linker tries
- to map in the DSO with the matching interface version. Aside from the
- restriction to a particular DSO _v_e_r_s_i_o_n, the effect of
- ssggiiddllooppeenn__vveerrssiioonn is identical to that of ddllooppeenn.
-
- These routines accept the following arguments:
-
- _p_a_t_h_n_a_m_e Specifies the path name of the object to be opened. It can
- be an absolute path or it can be relative to the current
- directory. If the value of _p_a_t_h_n_a_m_e is 0, ddllooppeenn makes the
- symbols contained in the original aa..oouutt file, and all of the
- objects that were loaded at program startup with the aa..oouutt
- file, available through ddllssyymm(3C).
-
- _m_o_d_e_1 Specifies when relocations can occur. This is the primary
- mode.
-
- When a DSO is brought into the address space of a process,
- it might contain references to symbols whose addresses are
- not known until the object is loaded. These references must
- be relocated before the symbols can be accessed. _m_o_d_e_1
- governs when these relocations occur.
-
- Specify either RRTTLLDD__LLAAZZYY or RRTTLLDD__NNOOWW for _m_o_d_e_1, as follows:
-
- _m_o_d_e_1 AArrgguummeenntt
-
- RRTTLLDD__LLAAZZYY Specifies that only references to data
- symbols are relocated when the object is
- loaded. References to functions are not
- relocated until a given function is invoked
- for the first time. This _m_o_d_e should result
- in the best performance because a process
- cannot reference all of the functions in any
- given shared object.
-
- RRTTLLDD__NNOOWW Specifies that all necessary relocations are
- performed when the object is first loaded.
- This might result in some wasted effort if
- relocations are performed for functions that
- are never referenced, but it is useful for
- programs that need to know as soon as an
- object is loaded that all symbols referenced
- during execution are available.
-
- _m_o_d_e_2 Refines the _m_o_d_e_1 specification. This is the secondary
- mode. You must include a _m_o_d_e_1 specification in order to
- specify a _m_o_d_e_2. The _m_o_d_e_2 argument must be preceded by an
- OR bar (||).
-
- Specify either RRTTLLDD__GGLLOOBBAALL or RRTTLLDD__LLOOCCAALL for _m_o_d_e_2. If
- _m_o_d_e_2 is not specified, RRTTLLDD__LLOOCCAALL is assumed. The _m_o_d_e_2
- specifications are as follows:
-
- _m_o_d_e_2 AArrgguummeenntt
-
- RRTTLLDD__GGLLOOBBAALL Modifies the treatment of the symbols in the
- DSO being opened to be identical to those of
- ssggiiddllaadddd(3C). With RRTTLLDD__GGLLOOBBAALL, the returned
- handle is less necessary than without
- RRTTLLDD__GGLLOOBBAALL because rrlldd(5) directly resolves
- references to symbols when RRTTLLDD__GGLLOOBBAALL is
- specified and ddllssyymm(3C) is not needed.
-
- RRTTLLDD__LLOOCCAALL Specifies that symbols in the DSO are not
- made globally visible. Default.
-
- For more information on the effects of RRTTLLDD__GGLLOOBBAALL and
- RRTTLLDD__LLOOCCAALL, see the NNAAMMEESSPPAACCEE IISSSSUUEESS and SSYYMMBBOOLL VVIISSIIBBIILLIITTYY
- sections of this man page.
-
- _v_e_r_s_i_o_n Specify a string that identifies the software version
- number. For more information on _v_e_r_s_i_o_n strings, see the
- lldd(1) man page and the _H_o_w _a_r_e _m_u_l_t_i_p_l_e _v_e_r_s_i_o_n_s _o_f _D_S_O_s
- _s_u_p_p_o_r_t_e_d? question on the ddssoo(5) man page.
-
- The _v_e_r_s_i_o_n should be a single version, such as ssggii22..00.
- Multiple versions are not accepted, meaning ssggii22..00::ssggii22..11 is
- incorrect as a value of the version string.
-
- While the effect of passing multiple versions in the string
- is undefined, the effect has been to treat ssggii22..00::ssggii22..11 as
- if it were ssggii22..00, unless LLLL__RREEQQUUIIRREE__MMIINNOORR was set in the
- _f_l_a_g_s argument. If multiple versions are in the _v_e_r_s_i_o_n
- argument, and LLLL__RREEQQUUIIRREE__MMIINNOORR is in the _f_l_a_g_s argument,
- version matching fails.
-
- _f_l_a_g_s Specify either LLLL__NNOONNEE or LLLL__RREEQQUUIIRREE__MMIINNOORR.
-
- Specifying LLLL__NNOONNEE means that the exact version must be
- present, but the minor version number is ignored in
- comparisons.
-
- Specifying LLLL__RREEQQUUIIRREE__MMIINNOORR means that only that precise
- major and minor version are accepted.
-
- NNAAMMEESSPPAACCEE IISSSSUUEESS
- This section does not address symbol resolution from ddllssyymm(3C). For
- details on its symbol resolution rules, see the ddllssyymm(3C) man page.
-
- Name resolution can become surprisingly complicated and nonintuitive
- in the presence of programs or DSOs that use ddllooppeenn, ssggiiddllaadddd(3C),
- ssggiiddllooppeenn__vveerrssiioonn, or LLLL__DDEELLAAYY__LLOOAADD (the --ddeellaayy__llooaadd option to the
- lldd(1) command).
-
- If there is only one definition of a symbol across all loaded DSOs,
- that definition is used if it is visible. For more information on
- visibility, see the SSYYMMBBOOLL VVIISSIIBBIILLIITTYY section of this man page.
-
- Name searches are done in the order of a single list, called the
- _r_l_d-_l_i_s_t. The first rld-list entry is the program itself. Following
- that is the list of DSOs currently in the runtime of the program. At
- program startup, a breadth-first list of DSOs in the program (and,
- recursively their library lists) is formed in the rld-list. No DSO is
- added to the rld-list twice. If there is a later occurrence of a DSO,
- the earlier occurrence is used. For an exception, see the NNOOTTEESS
- section of this man page. For any DSO library list entry marked
- LLLL__DDEELLAAYY__LLOOAADD, the referenced DSO is not loaded at program startup.
-
- An exception to the name search rule is made if a DSO is marked as
- DDTT__SSYYMMBBOOLLIICC. In this case, all name searches from within that DSO
- begin at the DSO itself and continue with the standard rld-list
- search. For more information on this, see the --BBssyymmbboolliicc option to
- the lldd(1) command.
-
- When, as a result of a call to a function in a DSO that has been
- loaded by using LLLL__DDEELLAAYY__LLOOAADD, that DSO is loaded and the new DSO is
- added at the end of the rld-list. If it has any entries in its
- library list that are not marked LLLL__DDEELLAAYY__LLOOAADD, the DSOs that are not
- delay-loaded are added recursively (breadth-first). Depending on the
- order of calls to delay-loaded DSOs, the order of DSOs on the rld-list
- might be different from one run of a program to the next.
-
- The order of DSOs in the rld-list might not match the order in any
- given library list because if a DSO is already in the rld-list, it is
- not added a second time to the rld-list.
-
- As a result of the rule that the search order is in rld-list order,
- the symbol that is found can be surprising. Consider a symbol AA found
- in DSOs BB and CC. Further, DSO BB is before DSO CC in EE's library list
- while DSO BB is after DSO CC in FF's library list. Neither DSO BB nor DSO
- CC are otherwise referenced. If DSO EE is opened by using ddllooppeenn with a
- _m_o_d_e of RRTTLLDD__GGLLOOBBAALL and it is opened before DSO FF, the AA from DSO BB is
- found by ddllssyymm(3C) from either handle. Similarly, if DSO FF is opened
- by using ddllooppeenn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL and it is opened before DSO
- EE, the AA from DSO CC is found by ddllssyymm(3C) from either handle.
- However, if only one of the DSOs EE or FF is opened by using ddllooppeenn with
- a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL, one gets DSO BB's AA from DSO EE's handle and one
- gets DSO CC's AA from DSO FF's handle.
-
- Note that ddllcclloossee(3C) does not cause any reordering of the rld-list.
- When the last handle (direct or indirect) on a DSO is closed with
- ddllcclloossee(3C), the DSO is removed from the rld-list. Before the final
- ddllcclloossee(3C), the DSO remains where it was on the rld-list.
-
- SSYYMMBBOOLL VVIISSIIBBIILLIITTYY
- DSOs loaded by a single invocation of ddllooppeenn can import symbols from
- one another or from any DSO that is globally visible, but DSOs loaded
- by one ddllooppeenn invocation cannot directly reference symbols from DSOs
- loaded by a different ddllooppeenn invocation. You can reference those
- symbols indirectly, however, by using ddllssyymm(3C).
-
- Globally visible DSOs are those added at program startup or via
- delay-load from a globally-visible object. In addition, any DSO added
- by ssggiiddllaadddd(3C), by ddllooppeenn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL, or by
- ssggiiddllooppeenn__vveerrssiioonn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL is globally visible.
- DSOs opened with RRTTLLDD__LLOOCCAALL are not globally visible.
-
- Even in a globally visible DSO, a symbol is invisible to any access
- from outside the DSO if the symbol is marked SSTTOO__HHIIDDDDEENN; for an
- example of this see the lldd(1) man page's descriptions for the
- --hhiiddddeenn__ssyymmbbooll or --hhiiddeess__ffiillee options. From within a DSO, all symbols
- in that DSO are visible. From within a DSO, all globally visible
- symbols are visible.
-
- Consider the following set of DSOs:
-
- ld -shared -all F.a -o F.so
- ld -shared -all G.a -o G.so
- ld -shared -all E.a F.so G.so -o E.so
- ld -shared -all H.a F.so -o H.so
-
- Consider the following conditions:
-
- * A program contains ddllooppeenn((""EE..ssoo"",,RRTTLLDD__LLAAZZYY)) and
- ddllooppeenn((""HH..ssoo"",,RRTTLLDD__LLAAZZYY)).
-
- * The program uses ddllssyymm to find functions through the two handles and
- calls these two functions.
-
- * Each of these calls a function that calls ffff(()) in FF..ssoo.
-
- * ffff(()) calls ffgg(()), which is defined only in GG..ssoo.
-
- Logically, you could assume that the call through the function
- accessed via EE..ssoo would resolve to ffgg(()) in GG..ssoo and that the call
- through the function accessed via HH..ssoo would result in an undefined
- function. However, rrlldd(5) does not attempt to determine (by walking
- the run-time stack or other means) the exact call stack to ffff(()). The
- call stack is not really enough; rrlldd(5) needs to know the handle used
- to derive the calls. The result of the call to ffgg(()) is undefined.
- What happens is that ffgg(()) in GG..ssoo is called, since such would be legal
- if the call path were through the handle in EE..ssoo. It is unwise to
- depend on such behavior.
-
- SSEEAARRCCHHIINNGG FFOORR DDSSOOss
- If other DSOs were link edited with _p_a_t_h_n_a_m_e when _p_a_t_h_n_a_m_e was built,
- those objects are automatically loaded by ddllooppeenn. This is subject to
- the LLLL__DDEELLAAYY__LLOOAADD library list flag. The directory search path that
- is used to find both _p_a_t_h_n_a_m_e and the other needed objects is the same
- as that used by rrlldd(5). In particular, _p_a_t_h_n_a_m_e is searched for in
- the following locations:
-
- * The directory specified by _p_a_t_h_n_a_m_e if it is not a simple file name
- (that is, it contains a slash (//) character). If it is not a simple
- file, _p_a_t_h_n_a_m_e is the only location searched; the other locations
- are ignored.
-
- * Any path specified via the --rrppaatthh argument to lldd(1) when the
- executable file was statically linked.
-
- * Any directory specified by the LLDD__LLIIBBRRAARRYY__PPAATTHH environment variable.
- This environment variable should contain a colon-separated list of
- directories, in the same format as the PPAATTHH variable (see sshh(1)).
- 64-bit programs examine the LLDD__LLIIBBRRAARRYY6644__PPAATTHH variable, and if it is
- not set, they examine the LLDD__LLIIBBRRAARRYY__PPAATTHH variable. New 32-bit ABI
- programs examine the LLDD__LLIIBBRRAARRYYNN3322__PPAATTHH variable and if it is not
- set, they examine the LLDD__LLIIBBRRAARRYY__PPAATTHH variable.
-
- All of these variables are ignored if the process is running sseettuuiidd
- or sseettggiidd (see eexxeecc(2)).
-
- * The default search paths. The paths differ depending on ABI. For
- information on the specific search paths, see the rrlldd(5) man page.
-
- If the process is running sseettuuiidd or sseettggiidd, the __RRLLDD__RROOOOTT,
- __RRLLDDNN3322__RROOOOTT, or __RRLLDD6644__RROOOOTT variable (the exact variable name depends
- on the ABI being used) is ignored (see rrlldd(5)).
-
- NNOOTTEESS
- You can open objects whose names resolve to the same absolute or
- relative path name any number of times by using ddllooppeenn. However, the
- referenced object is loaded only once into the address space of the
- current process. The same object referenced by two different path
- names, however, can be loaded multiple times. For example, given the
- object //uussrr//hhoommee//mmee//mmyylliibbss//mmyylliibb..ssoo, and assuming the current working
- directory is //uussrr//hhoommee//mmee//wwoorrkkddiirr, the following code results in
- mmyylliibbss..ssoo being loaded twice for the current process:
-
- ...
- void *handle1;
- void *handle2;
-
- handle1 = dlopen("../mylibs/mylib.so", RTLD_LAZY);
- handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
- ...
-
- On the other hand, given the same object and current working
- directory, if LLDD__LLIIBBRRAARRYY__PPAATTHH==//uussrr//hhoommee//mmee//mmyylliibbss, the following code
- results in mmyylliibbss..ssoo being loaded only once:
-
- ...
- void *handle1;
- void *handle2;
-
- handle1 = dlopen("mylib.so", RTLD_LAZY);
- handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
- ...
-
- Users who use ddllssyymm((00,,mmooddee)) to gain access to the symbol table of the
- aa..oouutt file itself should be aware that some symbols defined in the
- aa..oouutt file might not be available to the dynamic linker. The symbol
- table created by lldd(1) for use by the dynamic linker might contain
- only a subset of the symbols defined in the aa..oouutt file, specifically
- those referenced by the shared objects with which the aa..oouutt file is
- linked.
-
- Because there is no defined mechanism for dynamic loading in nonshared
- programs, a program built as nonshared (for example, by using cccc
- --nnoonn__sshhaarreedd) cannot usefully call ddllooppeenn, ddllssyymm(3C), ddlleerrrroorr(3C),
- ssggiiddllooppeenn__vveerrssiioonn, ssggiiddllaadddd(3C), or ddllcclloossee(3C). The dynamic loading
- routines are not included in the nonshared lliibbcc..aa file, so attempting
- to use them might result in a failure at link time. Any program built
- as nonshared that wishes to retain code that calls the dynamic loading
- routines must implement its own versions of ddllooppeenn, ddllssyymm(3C), and so
- on, and simply return appropriate error values to avoid the link-time
- errors. Note that building programs as nonshared is not generally
- recommended because not all libraries are available as nonshared.
-
- Using ddllcclloossee(3C) on a DSO, with __RRLLDD__AARRGGSS set to --ss in the
- environment, can cause surprising side effects. This is because
- ddllcclloossee(3C) forces many symbol GOT entries to be reset for
- re-lazy-evaluation. A result of this is that function pointers
- previously saved by the application or some library might hold values
- that could be obsolete or no longer correct. This is a problem for
- any ddllcclloossee(3C) process, but it is more serious when ddllcclloossee(3C) is
- used to close a handle on a globally-visible DSO.
-
- Symbol lookups proceed in order on a linear list, and a DSO is not
- opened twice with the same version number (unless different ddllooppeenn
- paths make the DSO name appear different to rrlldd(5)). When multiple
- ssggiiddllaadddd(3C) processes are executed and ddllcclloossee(3C) is used to close
- an earlier DSO, this can change the symbol to which a call is
- resolved. For more information, see the NNAAMMEESSPPAACCEE IISSSSUUEESS section.
-
- EEXXAAMMPPLLEESS
- The following specifies the RRTTLLDD__LLAAZZYY and RRTTLLDD__LLOOCCAALL modes:
-
- dlopen("X.so",RTLD_LAZY|RTLD_LOCAL);
-
- The following example program uses ddllooppeenn and was compiled with the
- --3322 compiler command line option:
-
- dltry.c:
- -------
- /* Error handling code not shown.
- */
- #include <dlfcn.h>
-
- typedef int (*xamplefuncptr)(int);
- int main()
- {
- void *handle;
- int i;
- xamplefuncptr fptr;
-
- handle = dlopen("greetings.so", RTLD_LAZY|RTLD_LOCAL);
- fptr = (xamplefuncptr)dlsym(handle, "greetings");
- i = (*fptr)(3);
- return 0;
- }
-
- greetings.c:
- -----------
- #include <stdio.h>
- int greetings(int num_greetings)
- {
- int i;
-
- for (i=0; i < num_greetings; i++)
- printf ("hello world\n");
- return 1;
- }
-
-
- % cc -32 -c dltry.c greetings.c
- % ld -32 -shared greetings.o -soname greetings.so -o greetings.so
- % cc -32 dltry.o
- % LD_LIBRARY_PATH=.
- % export LD_LIBRARY_PATH
- % a.out
- hello world
- hello world
- hello world
-
- RREETTUURRNN VVAALLUUEESS
- If _p_a_t_h_n_a_m_e cannot be found, cannot be opened for reading, is not a
- DSO, or if an error occurs during the process of loading _p_a_t_h_n_a_m_e or
- relocating its symbolic references, ddllooppeenn returns NNUULLLL. More
- detailed diagnostic information is available through ddlleerrrroorr(3C).
-
- SSEEEE AALLSSOO
- CCCC(1), cccc(1), ff7777(1), ff9900(1), lldd(1), sshh(1)
-
- eexxeecc(2)
-
- ddllcclloossee(3C), ddlleerrrroorr(3C), ddllssyymm(3C), ssggiiddllaadddd(3C),
-
- ddssoo(5), rrlldd(5)
-
- This man page is available only online.
-